/*
 * To change this license header, choose License Headers in Project Properties.
 * To change this template file, choose Tools | Templates
 * and open the template in the editor.
 */

package fr.inria.openmath.omapi;

/**
 *
 * @author Mr.Sam
 */
import java.io.*;
public interface Parser {

    /**
     * Allows an application to register a parse event handler.
     *
     * <p>If the application does not register an parse handler, all
     * events reported by the OpenMath parser will be silently
     * ignored (this is the default behaviour implemented by
     * ParserAdapter).</p>
     *
     * <p>Applications may register a new or different handler in the
     * middle of a parse, and the OpenMath parser must begin using the new
     * handler immediately.</p>
     *
     * @param handler The object handler.
     * @see ParserHandler
     * @see ParserAdapter
     */
    public void setParserHandler(ParserHandler handler) ;

    /**
     * Get the current parser handler.
     * @see setParserHandler
     */
    public ParserHandler getParserHandler() ;

    /**
     * Allows an application to register a parsing error event handler.
     *
     * <p>If the application does not register an error event handler,
     * all error events reported by the OpenMath parser will be silently
     * ignored, except for fatalError, which will throw a OMException
     * (this is the default behaviour implemented by ParserAdapter).</p>
     *
     * <p>Applications may register a new or different handler in the
     * middle of a parse, and the OpenMath parser must begin using the new
     * handler immediately.</p>
     *
     * @param handler The error handler.
     * @see ParserErrorHandler
     * @see OMException
     * @see ParserAdapter
     */
    public void setParserErrorHandler(ParserErrorHandler handler) ;

    /**
     * Get the current parser error handler.
     * @see setParserErrorHandler
     */
    public ParserErrorHandler getParserErrorHandler() ;



    /**
     * Initializes parsing on a new input source.
     *
     * <p>The application must use this method to instruct the OpenMath parser
     * to reset its state. Each time you change input source you need to call this function before using parse* methods.</P>
     *
     * @param source The input source.
     * @exception OMException Any OpenMath exception
     */
    public void initParse(InputStream source) throws OMException ;

    /**
     * Parses an OpenMath element.
     *
     * <p>The application can use this method to instruct the OpenMath parser
     * to begin parsing an OpenMath element from any valid input source (a
     * character stream, a byte stream...).</p>
     *
     * <p>Applications may not invoke this method while a parse is in
     * progress (they should create a new Parser for each
     * additional input source). Once a parse is complete, an
     * application may reuse the same Parser object to parse another
     * OpenMath object on the same input source or possibly with a
     * completly different input source.</p>
     *
     * @param source The input source.
     * @exception OMException Any OpenMath exception
     * @see #initParse
     * @see #setParserHandler
     * @see #setParserErrorHandler
     * @see fr.inria.openmath.omapi.ParserAdapter
     * @see fr.inria.openmath.omapi.ParserErrorAdapter
     */
    public void parseElement(InputStream source) throws OMException ;

    /**
     * Parses an OpenMath object.
     *
     * <p>The application can use this method to instruct the OpenMath parser
     * to begin parsing an OpenMath Object from any valid input source (a
     * character stream, a byte stream...).</p>
     *
     * <p>Applications may not invoke this method while a parse is in
     * progress (they should create a new Parser for each
     * additional input source). Once a parse is complete, an
     * application may reuse the same Parser object to parse another
     * OpenMath object on the same input source or possibly with a
     * completly different input source.</p>
     *
     * @param source The input source.
     * @exception OMException Any OpenMath exception
     * @see #initParse
     * @see #setParserHandler
     * @see #setParserErrorHandler
     * @see fr.inria.openmath.omapi.ParserAdapter
     * @see fr.inria.openmath.omapi.ParserErrorAdapter
     */
    public void parseObject(InputStream source) throws OMException ;

    /**
     * Parses OpenMath objects until source is exhausted.
     *
     * <p>The application can use this method to instruct the OpenMath parser
     * to begin parsing OpenMath Objects from any valid input source (a
     * character stream, a byte stream...).</p>
     *
     * <p>Applications may not invoke this method while a parse is in
     * progress (they should create a new Parser for each
     * additional input source). Once a parse is complete, an
     * application may reuse the same Parser object to parse another
     * OpenMath object on the same input source or possibly with a
     * completly different input source.</p>
     *
     * @param source The input source.
     * @exception OMException Any OpenMath exception
     * @see #initParse
     * @see #setParserHandler
     * @see #setParserErrorHandler
     * @see fr.inria.openmath.omapi.ParserAdapter
     * @see fr.inria.openmath.omapi.ParserErrorAdapter
     */
    public void parse(InputStream source) throws OMException ;


}
